QRZ! Ham Radio 5

home *** CD-ROM | disk | FTP | other *** search

/ QRZ! Ham Radio 5 / QRZ Ham Radio Callsign Database - Volume 5.iso / files / tcpip / amiga / mb1705.exe / BBS_SPEC.DOC < prev next >

Wrap

Text File | 1994-05-13 | 24.5 KB | 862 lines

Changes: CTL-C not really restricted character? LF not used as alternate EOL Added info from AA4RE on "M in SID". Added info from W0RLI on "X in SID". Legal character set for BID? ... Hank BBS Interface Specification Working Draft 11/28/93 Introduction Section 1 - Establishing connection Section 2 - Forwarding Section 3 - Reverse forwarding Section 4 - Forwarding to old BBSs Section 5 - Error Conditions Section 6 - BNF Summary Section 7 - Feature Letter Use Current mailing list BBS_authors@arasmith.com bob@arasmith.com (Bob Arasmith, N0ARY) hank_oredson@mentorg.com (Hank Oredson, W0RLI) wd6cmu@netcom.com (Eric Williams, WD6CMU) enge@almaden.ibm.com (Roy Engehausen, AA4RE) 71151.720@CompuServe.COM (Victor Poor, W5SMM) blloyd@axion.bt.co.uk (Brian Lloyd, G1NNA) map@hopper.cba.csuohio.edu (Mike Pechura, WA8BXN) durham@w2xo.pgh.pa.us (James Durham, W2XO) johan@ece.orst.edu (Johannes Reinalda, WG7J) trentin@enac.dgac.fr (to J-P Roubelat, F6FBB) sproul@sproul.com (Mark Sproul, KB2ICI) mike@km6px.arasmith.com (Mike Stickney, KM6PX) 70007.1365@compuserve.com (Ed Juge, W5TOO) 73126.3260@compuserve.com (Craig McCartney, WA8DRZ) bbr77@aol.com (Brian Riley, KA2BQE) Via US Mail Michael Jaggers, WB4TTZ 1377 Columbia Ave, Franklin, TN 37064 Introduction - This document is meant to define the interaction between two BBSs exchanging messages. It is not the goal of the document to specify the interface of the future but merely represent what a BBS can be expected to see at the current time. It is hoped that this specification will be followed by another that defines the base rules for all BBS programs to adopt. This should eliminate the current problems with incompatibilities and overloaded operators. If you create a BBS to this specification you should be able to interconnect with virtually any BBS currently in use. Any extensions you add will put you at risk, the subsequent spec is to identify these areas. In brief the following sequence of events takes place when the BBSs connect for forwarding: Master System Slave System ------------ -------------- {Connect} [SID] N9ZZZ > [SID] > SB ARES @ ALLCA < W7ZZZ $ARES0108 OK message subject message routing headers message body /EX > SB WANT @ ALLUS < W8AAA $1029_N0XYZ NO > F> SP WA2ABC @ N2AAA < N9AAA OK message subject message routing headers message body /EX F> {Disconnect} This represents a simple example of connecting, establishing a common protocol, forwarding and reverse forwarding. This document will look more closely at each of these phases. In the text the BBS initiating the connect will be referred to as the MASTER and the remote BBS will be referred to as the SLAVE. Each command and exchange will be presented in BNF (Backus-Naur Form) which is a context-free grammar widely used to describe computer language syntax. All commands and fields are case insensitive. Meta-syntactic information [x] = Optional: zero or one x (x y) = Grouping: treat multiple tokens as a single token <> = Set Characters: NUL = <0x00> CNTRL_C = <0x03> TAB = <0x09> CR = <0x0D> LF = <0x0A> CNTRL_Z = <0x1A> SP = <0x20> Character sets: ALPHA = <'A'-'Z'> DIGIT = <'0'-'9'> ALNUM = ALPHA | DIGIT ASCII = <0x20-0x7F> SPACE = SP | TAB 8BIT = <0x01 - 0xff, except CR, LF, CTRL_Z> Character sequences: EOL = CR | CR LF NUMBER = DIGIT | NUMBER DIGIT WHITE = SPACE | WHITE SPACE ASCII_STR = ASCII | ASCII_STR ASCII ALNUM_STR = ALNUM | ALNUM_STR ALNUM 8BIT_STR = 8BIT | 8BIT_STR 8BIT Throughout this document we will present a verbose translation of the grammar highlighting any points that may not be obvious but could have significant affect. There will also be examples illustrating what can actually be expected. Section 1 - Establishing connection When connecting to a BBS the first line the BBS sends must be the SID (System IDentifier). The SID is used to determine what features are supported by BBS. The existence of the SID implies that the system supports reverse forwarding and OK/NO message rejection. There still exist old BBS codes which do not present a SID at connect. Refer to Section 4 for information on forwarding to these old style BBS sytems. SID sent by both MASTER and SLAVE AUTHOR_ID = <ASCII_STR, except '[', ']' and '-'> AUTHOR_DATA = <ASCII_STR, except '[' and ']'> FEATURE = ALPHA [DIGIT] FEATURE_LIST = FEATURE | FEATURE_LIST FEATURE SID = "[" AUTHOR_ID "-" [AUTHOR_DATA "-"] FEATURE_LIST [$]"]" EOL The AUTHOR_ID and FEATURE_SET must be present. If the optional AUTHOR_DATA is present it must be separated from the other two fields by a '-'. AUTHOR_DATA may contain the '-' character. The AUTHOR_ID and AUTHOR_DATA are typically a portion of the authors callsign or BBS name and version number, respectively. Each FEATURE consists of a letter, denoting the feature and an optional number, denoting the feature level. The absence of a version number implies version zero. If BID's are supported, '$' must be the last symbol in the FEATURE_SET. The recommended minimal support is BID and Hierarchical location identifiers. These are necessary for the proper operation of the network. EXAMPLE [ZFJ-2.3-H$] The original prompt received from the SLAVE BBS may contain additional information intended for users. As soon as the SID is received by the SLAVE BBS it should respond with an abbreviated PROMPT, with the ASCII_STR field being empty. Section 2 - Forwarding A message can either be rejected or accepted by the SLAVE. There are many reasons that the SLAVE my choose to reject a message but the most common will be duplicate bid, indicating the SLAVE already has the message. Here is an overview of the exchange. ACCEPT EXCHANGE: MASTER SLAVE ------ ----- PROMPT SEND_CMD RESPONSE (OK) MESSAGE COMMENT PROMPT REJECT EXCHANGE: MASTER SLAVE ------ ----- PROMPT SEND_CMD RESPONSE (NO) PROMPT The SLAVE indicates it's prepared to accept a command by issuing a PROMPT. The PROMPT is also used as an an acknowledgement that the last message has be received. The MASTER initiates the message exchange by issuing a a SEND_CMD. This command contains all the information necessary for the SLAVE to decide whether to ACCE or REJECT the message. It contains message type, destination, originator and possibly a bid. COMMENT = <ASCII_STR, except '>'> PROMPT = [COMMENT] ">" EOL TYPE = 'B' | 'P' | 'T' CALLSIGN = <ASCII_STR, except '@', '.', max length 6> LOC = <ASCII_STR, except '@', '.', max length 6> HLOC = LOC | <HLOC "." LOC, max length 31> BBS = CALLSIGN ["." HLOC] TO = CALLSIGN [WHITE "@" WHITE BBS] FROM = CALLSIGN BID = <ASCII_STR, max length 12> SEND_CMD = "S" TYPE WHITE TO [WHITE "<" WHITE FROM] [WHITE "$" BID] HLOC is the hierarchical location of the system. It is defined by the document "INTERNATIONAL ROUTING DESIGNATORS", ARRL Networking Conference Proceedings xxx. The TO field commonly takes the following forms: callsign @ BBS.hloc ; N6ZFJ @ N6QMY.CA.USA.NA category @ distrib ; WANT @ ALLCA category @ BBS.hloc ; WANT @ N6QMY.CA.USA.NA category @ distib.hloc ; INFO @ ALLCA.CA.USA.NA The first two are seen most often, but the other two forms are seen. The first two forms are also normally associated with the message type of PERSONAL and BULLETIN respectively. White space is required on either side of the '@' and between the '<' and the senders callsign. There cannot be white space between the '$' and the BID. EXAMPLE SB WANT @ ALLSCV < N6ZFJ $2345_N6QMY A "BID" (Bulletin IDentifier) is associated with each Bulletin, and may be associated with any Personal message. If a BID is not given explicitly when the message is entered into the system, and the message type requires a BID, one is created automatically from the message number and callsign of the system into which the message was initially entered. NOTE: It is suggested that a generated BID have the form nnn_BBS, where nnn is the message number at the originating BBS system, and BBS is the callsign of the originating BBS system. COMMON_BID = MSG_NUM "_" CALLSIGN BBS codes are free to create whatever form they wish as long as the length doesn't exceed 12 characters. Messages to a distribution, whether they are bulletins or personal messages, must have a BID. Personal messages to a specific user may carry a BID if the user supplied one, but will not be given a default BID. NTS message never carry a BID. The SLAVE BBS determines from the SEND_CMD whether or not to accept the message. The reasons for rejection is usually that the message already exists on the SLAVE system (i.e. a duplicate BID), or possibly a system related problem. Sent by SLAVE in response to SEND_CMD (or by MASTER if in reverse forward mode). RESPONSE = ACCEPT | REJECT ACCEPT = "OK" [ WHITE COMMENT ] EOL REJECT = "N" [ "O" ] [ WHITE COMMENT ] EOL NOTE: The syntax of responses has grown in a random fashion. Many BBS programs expect to see the entire words "OK" and "NO" while others simply look at the first letter. It is suggested that new BBS codes should present the words "NO" and "OK", but look for only the first letter. Doing so should ensure compatibility with existing BBS codes. EXAMPLE Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY Slave: NO duplicate bid Slave: > Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY Slave: OK #32190 Master: message body Master: /EX Slave: Message being held for sysop review Slave: > It is required that the "OK" and "NO" strings be followed by white space or EOL. Some BBS programs will fail to recognize them otherwise. EXAMPLE Master: SB WANT @ ALLCAN < N6ZFJ $4567_N0ARY Slave: NO, already have it Slave: > This would fail with some existing BBS codes due to the comma following the "NO" string. If the SLAVE BBS responds with a REJECT condition the message should not be sent and the MASTER should ignore any response from the SLAVE until PROMPT is encountered. The MASTER can then submit a new SEND_CMD, initiate reverse forwarding or disconnect. Once the SLAVE has issued the ACCEPT response, the MASTER BBS should immediately send the message subject, routing headers, message body and EOM. The SLAVE will acknowledge with PROMPT once it receives an EOM. Message Routing Header SUBJECT = <ASCII_STR, max length 79> EOL YEAR = DIGIT DIGIT MONTH = DIGIT DIGIT DAY = DIGIT DIGIT HOUR = DIGIT DIGIT MINUTE = DIGIT DIGIT STAMP = "R:" YEAR MONTH DAY "/" HOUR MINUTE ["Z"] MSG_NUM = <NUMBER, range 1 - 65535 (0xFFFF)> HEADER1 = STAMP WHITE MSG_NUM "@" BBS EOL HEADER2 = STAMP WHITE "@:" BBS WHITE [ASCII_STR] "#:" MSG_NUM [ASCII_STR] HEADER = HEADER1 | HEADER2 Message structure HEADERS = HEADER | HEADERS HEADER EOM = (CNTRL_Z EOL) | (EOL "/EX" EOL) BODY = 8BIT_STR | BODY EOL 8BIT_STR MESSAGE = SUBJECT [HEADERS] EOL [BODY] EOM EXAMPLE Example message R:930108/1729 @:N6QMY.#NOCAL.CA.USA.NA Fremont #:1114 Z:94536 R:930108/1259 1530@KA6FUB.#NOCAL.CA.USA.NA R:930107/1638z @:WD6CMU.#NOCAL.CA.USA.NA "OSKbox" #:10576 Z:94805 R:930107/1045 50724@WX3K.#NOCAL.CA.USA.NA message body will go here, the blank line above separates the body from the routing headers. When the body is through it should be terminated as follows: /EX NOTE: Both forms of the header described above are seen, and should be parsed. In either case there may be comments found at the end of the header line, or between the BBS and the MSG_NUM entries in HEADER2. HEADER2 is derived from the header form used in early BBS codes. it allows addtional information to be passed in the header and parsed if desired. Some examples of these additional fields seen are: Z:zipcode O:orginator $:bid C:name_of_sysops_cat NOTE: The time stamp in the routing header must be in GMT. Some existing BBS codes provide the time stamp in other than GMT, and may include a time zone indicator after the time stamp. This should be considered in the design of header parsers. Each system that handles the message places it's routing header at the top of the message headers before passing the message to the next BBS. The headers must begin in column 1. A blank line separates the routing headers from the body of the message. The last (oldest) routing header shows the BBS where the message originated. This header is the only source for this information. The information about the originating BBS is used to create a return address for reply messages. Here are two examples of the same header, in the two different formats: R:930101/0000 1530@KA6FUB.#NOCAL.CA.USA.NA R:930101/0000 @:KA6FUB.#NOCAL.CA.USA.NA #:1530 These examples show the different syntax for the message number and originating BBS address. All fields not shown in the examples are optional at the discretion of the sysop. Section 3 - Reverse forwarding Once all messages have either been successfully forwarded from the MASTER to the SLAVE, or been rejected by the SLAVE, the MASTER may accept messages from the SLAVE. i.e. the MASTER and SLAVE exchange roles. This is called "reverse forwarding". ACCEPT EXCHANGE: MASTER SLAVE ------ ----- PROMPT ">" REV_FWD "F>" SEND_CMD RESPONSE "OK" MESSAGE COMMENT REV_FWD "F>" REJECT EXCHANGE: MASTER SLAVE ------ ----- PROMPT ">" REV_FWD "F>" SEND_CMD RESPONSE "NO" REV_FWD "F>" The MASTER indicates that it is ready to accept a message by answering the SLAVE's PROMPT, ">", with a REV_FWD command, "F>". At that point the SLAVE issues a SEND_CMD and the process continues as described in section 2 but with the rolls of MASTER and SLAVE reversed. The only difference is that the MASTER will always respond with REV_FWD in place of PROMPT to indicate successful transfer. REV_FWD = "F>" EOL The reverse forwarding phase is optional and is under the control of the MASTER. It can be terminated by any of the following: SLAVE disconnects SLAVE sends anything other than a legal SEND_CMD MASTER disconnects MASTER sends anything other than "F>". Section 4 - Forwarding to old BBSs If the SLAVE does not return a SID then it is assumed that it will not support BIDs nor OK/NO message rejection. The SLAVE indicates it is prepared to accept a command by issuing a PROMPT. This PROMPT is also an acknowledgement that the last message has been received. The MASTER initiates the message exchange by issuing a SEND_CMD with no HLOC or BID. The SLAVE has no way to reject the message so the MASTER proceeds to send the message subject and body without expecting acknowlegement from the SLAVE. Since the SLAVE assumes a user is entering the message, it will display prompts to lead the user through the message sending process, asking for a subject, prompting for the message body, etc. The MASTER should consider this text to be part of the PROMPT and ignore it. As in Section 2, the MASTER waits until PROMPT is received. This is the acknowledgement that the message has been recieved and the next message can be sent. When the MASTER has no additional messages to send it disconnects from the SLAVE. Reverse forwarding is not supported in this situation. Section 5 - Error Conditions When an error of any nature is detected by either the MASTER or the SLAVE, that station will disconnect at once, without issuing a PROMPT. Section 6 - BNF Summary Meta-syntactic information. [x] = Optional Zero or one x. (x y) = Grouping. Treat multiple tokens as single token. <> = Set. Characters of interest. TAB = <0x09> LF = <0x0a> CR = <0x0d> CNTRL_Z = <0x1a> SP = <0x20> Character sets of interest. ALPHA = <'A' - 'Z', 'a' - 'z'> DIGIT = <'0' - '9'> ALNUM = ALPHA | DIGIT ASCII = <0x20 - 0x7f> SPACE = SP | TAB 8BIT = <0x01 - 0xff, except CR, LF, CTRL_Z> Character sequences of interest. EOL = CR | CR LF NUMBER = DIGIT | NUMBER DIGIT WHITE = SPACE | WHITE SPACE ASCII_STR = ASCII | ASCII_STR ASCII ALNUM_STR = ALNUM | ALNUM_STR ALNUM 8BIT_STR = 8BIT | 8BIT_STR 8BIT System identifier syntax. AUTHOR_ID = <ASCII_STR, except '[', ']', '-'> AUTHOR_DATA = <ASCII_STR, except '[', ']'> FEATURE = ALPHA [DIGIT] FEATURE_LIST = FEATURE | FEATURE_LIST FEATURE SID = "[" AUTHOR_ID ["-" AUTHOR_DATA] "-" FEATURE_LIST "]" EOL System Prompt syntax. COMMENT = <ASCII_STR, except '>'> PROMPT = [COMMENT] ">" EOL Send Command syntax. TYPE = 'B' | 'P' | 'T' CALLSIGN = <ASCII_STR, except '@', '.', ' ', max length 6> LOC = <ASCII_STR, except '@', '.', ' ', max length 6> HLOC = <LOC | HLOC "." LOC, max length 31> BBS = CALLSIGN ["." HLOC] TO = CALLSIGN [("@" | WHITE "@" WHITE) BBS] FROM = CALLSIGN BID = <ASCII_STR, except ' ', max length 12> SEND = "S" TYPE WHITE TO [WHITE "<" WHITE FROM] [WHITE "$" [BID]] Message syntax. SUBJECT = <ASCII_STR, max length 79> EOL YEAR = DIGIT DIGIT MONTH = DIGIT DIGIT DAY = DIGIT DIGIT HOUR = DIGIT DIGIT MINUTE = DIGIT DIGIT STAMP = "R:" YEAR MONTH DAY "/" HOUR MINUTE MSG_NUM = <NUMBER, range 1 - 65535> HEADER1 = STAMP WHITE MSG_NUM "@" BBS EOL HEADER2 = STAMP WHITE "@:" BBS WHITE [ASCII_STR] "#:" MSG_NUM [ASCII_STR] HEADER = HEADER1 | HEADER2 HEADERS = HEADER | HEADERS HEADER BODY = 8BIT_STR | BODY EOL 8BIT_STR EOM = (CTRL_Z EOL) | (EOL "/EX" EOL) MESSAGE = SUBJECT [HEADERS] EOL [BODY] EOM Standard message identification syntax. MSG_ID = MSG_NUM "_" CALLSIGN Section 7 - Feature Letter Use Feature $: Supports BIDs. Feature A: F6FBB - Acknowledge for personal messages. Feature B: F6FBB - Binary messages supported. Feature C: Obsolete: Supports automatic distribution of current date / time. (W0RLI, K0ZXF) Feature F: F6FBB - Batch forwarding protocol. Feature H: Supports Hierarchical Location designators. Feature I: Some transport mechanisms do not identify the calling station in the protocol as AX25 does. To handle this situation, a "null command" is defined as a line beginning with ';'. This allows the sending station to send callsigns to satisfy the regulations for station identification. EXAMPLE ; W5SMM de W0RLI The receiving station must ignore such lines. Feature L: G1nna - Compression. Feature M: For AA4RE systems: Basic level ("M0") MID = message identifier Every message has a MID. The MID looks like a "generated" BID (example 12345_AA4RE). The "M" letter in the SID indicates that a MID is to be transmitted with messages that have no BID. Processing: If a send command is received by a BBS with a MID, the program should determine if it is a duplicate. If it is, the program should respond with the usual "NO" as if it was matching a BID. Feature R: AA4RE - Extended reject responses. OK Yes, send to me. Note that no number is required. This may help eliminate phantom message numbers. NO This is a real dupe REJECT I can't handle this LATER Send to me later ... The LATER is useful when you are already receiving a bulletin on one connect and someone else tries to send you the same bulletin. REJECTed messages should be called to the attention of the SYSOP to see why the reject occurs. The difference between NO and REJECT is whether or not SYSOP attention is needed. Abreviations are alloed: 1 Letter only ... O N L R There must be a blank after the word or letter. This one is fine: N Already have it. This one is not correct: REJECT, Something wrong The comma is not allowed. Feature S: AA4RE - Extended "S" commands. Feature X: W0RLI - Supports ihave/iwant compressed batch forwarding. A standard for Data compression during the forwarding of messages in the Amateur Radio BBS Network. o ihave/iwant variable batch size protocol o Feature letter X, commands SS, SX, SY. o lzh compression ---------------------------------------------------------------------------- Command Definitions and BNF description. ---------------------------------------------------------------------------- N = INTEGER, size 32 bits. protocol = TBD batch_size = N file_size = N msg_count = <0 - 25> cksum = <file checksum> id = BID | MID CR ids = id | ids id byte = <0x00 - 0xff) bytes = byte | bytes byte ihave = "SX " msg_count [" " protocol] [" " batch_size] CR [ids] iwant = "SY " msg_count CR [ids] isend = "SS " file_size [" " cksum] CR bytes For ihave: Protocol and batch_size not used in initial implementation. Default protocol is: lzh compressed export/import file. For iwant: SY means want only these. Note that the SS command must terminate with CR, without LF. The optional checksum is computed by summing all the bytes in the file as unsigned integers. Example code: { int byte; unsigned int sum; sum = 0; for (all bytes in file) sum += byte; } RFC-822 header fields used are: To: From: Subject: Message-ID: X-msgtype: X-BID: ---------------------------------------------------------------------------- The basic interchange (example): ---------------------------------------------------------------------------- bn are BIDs (or MID if message has no BID). m: is master, s: is slave. m: SX 5 m: b1 m: b2 m: b3 m: b4 m: b5 s: SY 3 s: b1 s: b3 s: b5 m: SS 26545 m: <sends 26545 byte file> In the case of any error, the station noticing the error must disconnect. ---------------------------------------------------------------------------- With more detail of one implementation (MB/SERVER processing) ---------------------------------------------------------------------------- Maximum batch size defined globally (default), and per link. Ability to turn compression on/off (add/drop feature X in SID). From sending side: MB: Scan messages to find a batch just larger than max batch size. Keep record numbers and cc: id in list. Send ihave. Receive iwant. Mark all messages in ihave and not in iwant as forwarded (dup bid). Pass iwant list to SERVER in file. Wait for server acknowledge. SERVER: Create export file. Compress export file. Signal MB that compressed file ready to send. MB: Send isend, send the file. Receive prompt. Mark all messages in iwant as forwarded. From receiving side: MB: Receive ihave. Check bids in ihave. For all non-dup bids, make iwant list. Send iwant. Receive compressed file. Signal SERVER import file available. Send prompt. SERVER: Decompress file, import messages. Section 8 - Import / Export files. Import/Export files may contain any number of messages. Each message is terminated by "/EX" EOL RFC-822 header use in import/export files. The standard RFC-822 keywords which must be supported are: To: From: Subject: Message-ID: cc: Extension keywords which must be supported are: X-msgtype: (W0RLI) X-BBS-Msg-Type: (JNOS) X-BID: (W0RLI) X-BBS-Hold: (JNOS) X-Forwarded-To: (JNOS) END OF SPEC